علاقات مُسلسلات بايثون DRF: إتقان تسلسل الكائنات المتداخلة

يوفر Django REST Framework (DRF) نظامًا قويًا ومرنًا لبناء واجهات برمجة التطبيقات (APIs) على الويب. يعد التعامل مع العلاقات بين نماذج البيانات جانبًا حاسمًا في تطوير واجهات برمجة التطبيقات، وتوفر مُسلسلات DRF آليات قوية لتسلسل وفك تسلسل الكائنات المتداخلة. يستكشف هذا الدليل الطرق المختلفة لإدارة العلاقات في مُسلسلات DRF، مع تقديم أمثلة عملية وأفضل الممارسات.

فهم علاقات المُسلسل

في قواعد البيانات العلائقية، تحدد العلاقات كيفية ربط الجداول أو النماذج المختلفة. تحتاج مُسلسلات DRF إلى عكس هذه العلاقات عند تحويل كائنات قاعدة البيانات إلى JSON أو تنسيقات بيانات أخرى لاستهلاك API. سنغطي الأنواع الثلاثة الأساسية للعلاقات:

• ForeignKey (واحد إلى متعدد): يرتبط كائن واحد بعدة كائنات أخرى. على سبيل المثال، يمكن لمؤلف واحد كتابة العديد من الكتب.
• ManyToManyField (متعدد إلى متعدد): ترتبط كائنات متعددة بكائنات أخرى متعددة. على سبيل المثال، يمكن لعدة مؤلفين التعاون في تأليف كتب متعددة.
• OneToOneField (واحد إلى واحد): يرتبط كائن واحد بشكل فريد بكائن آخر. على سبيل المثال، غالبًا ما يتم ربط ملف تعريف المستخدم بواجهة المستخدم (user account) بشكل واحد إلى واحد.

التسلسل المتداخل الأساسي مع ForeignKey

لنبدأ بمثال بسيط لتسلسل علاقة ForeignKey. ضع في اعتبارك هذه النماذج:

from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)
    country = models.CharField(max_length=50, default='USA') # إضافة حقل country للسياق الدولي

    def __str__(self):
        return self.name

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')
    publication_date = models.DateField()

    def __str__(self):
        return self.title

لتسلسل نموذج `Book` مع بيانات `Author` المرتبطة به، يمكننا استخدام مُسلسل متداخل:

from rest_framework import serializers

class AuthorSerializer(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = ['id', 'name', 'country']

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer(read_only=True) # تم التغيير من PrimaryKeyRelatedField

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

في هذا المثال، يتضمن `BookSerializer` حقل `AuthorSerializer`. `read_only=True` يجعل حقل `author` للقراءة فقط، مما يمنع تعديل المؤلف عبر نقطة نهاية الكتاب. إذا كنت بحاجة إلى إنشاء أو تحديث الكتب بمعلومات المؤلف، فستحتاج إلى التعامل مع عمليات الكتابة بشكل مختلف (انظر أدناه).

الآن، عند تسلسل كائن `Book`، سيتضمن ناتج JSON تفاصيل المؤلف الكاملة المتداخلة داخل بيانات الكتاب:

{
    "id": 1,
    "title": "The Hitchhiker's Guide to the Galaxy",
    "author": {
        "id": 1,
        "name": "Douglas Adams",
        "country": "UK"
    },
    "publication_date": "1979-10-12"
}

تسلسل علاقات ManyToManyField

دعنا ننظر إلى علاقة `ManyToManyField`. لنفترض أن لدينا نموذج `Category` ويمكن أن ينتمي كتاب إلى فئات متعددة.

class Category(models.Model):
    name = models.CharField(max_length=100)

    def __str__(self):
        return self.name

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')
    categories = models.ManyToManyField(Category, related_name='books')
    publication_date = models.DateField()

    def __str__(self):
        return self.title

يمكننا تسلسل الفئات باستخدام `serializers.StringRelatedField` أو `serializers.PrimaryKeyRelatedField`، أو إنشاء مُسلسل متداخل.

class CategorySerializer(serializers.ModelSerializer):
    class Meta:
        model = Category
        fields = ['id', 'name']

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer(read_only=True)
    categories = CategorySerializer(many=True, read_only=True) # many=True ضروري لـ ManyToManyField

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'categories', 'publication_date']

الوسيط `many=True` ضروري عند تسلسل `ManyToManyField`. يخبر هذا المُسلسل بتوقع قائمة بكائنات الفئات. سيبدو الناتج كالتالي:

{
    "id": 1,
    "title": "Pride and Prejudice",
    "author": {
        "id": 2,
        "name": "Jane Austen",
        "country": "UK"
    },
    "categories": [
        {
            "id": 1,
            "name": "Classic Literature"
        },
        {
            "id": 2,
            "name": "Romance"
        }
    ],
    "publication_date": "1813-01-28"
}

تسلسل علاقات OneToOneField

بالنسبة لعلاقات `OneToOneField`، فإن النهج مشابه لـ ForeignKey، ولكن من المهم التعامل مع الحالات التي قد لا يكون فيها الكائن المرتبط موجودًا.

from django.contrib.auth.models import User

class UserProfile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE, related_name='profile')
    bio = models.TextField(blank=True)
    location = models.CharField(max_length=100, blank=True, default='Global') # إضافة location للسياق الدولي

    def __str__(self):
        return self.user.username

class UserProfileSerializer(serializers.ModelSerializer):
    class Meta:
        model = UserProfile
        fields = ['id', 'bio', 'location']

class UserSerializer(serializers.ModelSerializer):
    profile = UserProfileSerializer(read_only=True)

    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'profile']

سيكون الناتج:

{
    "id": 1,
    "username": "johndoe",
    "email": "john.doe@example.com",
    "profile": {
        "id": 1,
        "bio": "Software Engineer.",
        "location": "London, UK"
    }
}

التعامل مع عمليات الكتابة (الإنشاء والتحديث)

تركز الأمثلة أعلاه بشكل أساسي على التسلسل للقراءة فقط. للسماح بإنشاء أو تحديث الكائنات المرتبطة، تحتاج إلى تجاوز طرق `create()` و `update()` في المُسلسل الخاص بك.

إنشاء كائنات متداخلة

لنفترض أنك تريد إنشاء كتاب ومؤلف جديد في نفس الوقت.

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer()

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

    def create(self, validated_data):
        author_data = validated_data.pop('author')
        author = Author.objects.create(**author_data)
        book = Book.objects.create(author=author, **validated_data)
        return book

في طريقة `create()`، نستخرج بيانات المؤلف، وننشئ كائن `Author` جديد، ثم ننشئ كائن `Book`، مع ربطه بالمؤلف الذي تم إنشاؤه حديثًا.

هام: ستحتاج إلى التعامل مع أخطاء التحقق المحتملة في `author_data`. يمكنك استخدام كتلة try-except ورفع `serializers.ValidationError` إذا كانت بيانات المؤلف غير صالحة.

تحديث الكائنات المتداخلة

بالمثل، لتحديث كتاب ومؤلفه:

class BookSerializer(serializers.ModelSerializer):
    author = AuthorSerializer()

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

    def update(self, instance, validated_data):
        author_data = validated_data.pop('author', None)

        if author_data:
            author = instance.author
            for attr, value in author_data.items():
                setattr(author, attr, value)
            author.save()

        for attr, value in validated_data.items():
            setattr(instance, attr, value)
        instance.save()

        return instance

في طريقة `update()`، نسترجع المؤلف الحالي، ونحدث سماته بناءً على البيانات المقدمة، ثم نحدث سمات الكتاب. إذا لم يتم توفير `author_data` (مما يعني أن المؤلف لا يتم تحديثه)، فإن الكود يتخطى قسم تحديث المؤلف. القيمة الافتراضية `None` في `validated_data.pop('author', None)` ضرورية للتعامل مع الحالات التي لا تتضمن فيها بيانات المؤلف في طلب التحديث.

استخدام `PrimaryKeyRelatedField`

بدلاً من المُسلسلات المتداخلة، يمكنك استخدام `PrimaryKeyRelatedField` لتمثيل العلاقات باستخدام المفتاح الأساسي للكائن المرتبط. هذا مفيد عندما تحتاج فقط إلى الرجوع إلى معرف الكائن المرتبط ولا تريد تسلسل الكائن بأكمله.

class BookSerializer(serializers.ModelSerializer):
    author = serializers.PrimaryKeyRelatedField(queryset=Author.objects.all())

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

الآن، سيحتوي حقل `author` على معرف المؤلف:

{
    "id": 1,
    "title": "1984",
    "author": 3,  // معرف المؤلف
    "publication_date": "1949-06-08"
}

للإنشاء والتحديث، ستمرر معرف المؤلف في بيانات الطلب. يضمن `queryset=Author.objects.all()` أن المعرف المقدم موجود في قاعدة البيانات.

استخدام `HyperlinkedRelatedField`

يمثل `HyperlinkedRelatedField` العلاقات باستخدام ارتباطات تشعبية لنقطة نهاية API للكائن المرتبط. هذا شائع في واجهات برمجة التطبيقات التي تدعم الوسائط المتعددة (HATEOAS).

class BookSerializer(serializers.ModelSerializer):
    author = serializers.HyperlinkedRelatedField(view_name='author-detail', read_only=True)

    class Meta:
        model = Book
        fields = ['id', 'title', 'author', 'publication_date']

الوسيط `view_name` يحدد اسم العرض الذي يتعامل مع الطلبات للكائن المرتبط (مثل `author-detail`). ستحتاج إلى تعريف هذا العرض في ملف `urls.py` الخاص بك.

سيتضمن الناتج عنوان URL يشير إلى نقطة نهاية تفاصيل المؤلف:

{
    "id": 1,
    "title": "Brave New World",
    "author": "http://example.com/api/authors/4/",
    "publication_date": "1932-01-01"
}

تقنيات واعتبارات متقدمة

• خيار `depth`: في `ModelSerializer`، يمكنك استخدام خيار `depth` لإنشاء مُسلسلات متداخلة تلقائيًا لعلاقات ForeignKey حتى عمق معين. ومع ذلك، يمكن أن يؤدي استخدام `depth` إلى مشاكل في الأداء إذا كانت العلاقات معقدة، لذا يوصى بشكل عام بتعريف المُسلسلات بشكل صريح.
• `SerializerMethodField`: استخدم `SerializerMethodField` لإنشاء منطق تسلسل مخصص للبيانات المرتبطة. هذا مفيد عندما تحتاج إلى تنسيق البيانات بطريقة معينة أو تضمين قيم محسوبة. على سبيل المثال، يمكنك عرض اسم المؤلف الكامل بترتيبات مختلفة بناءً على المنطقة. بالنسبة للعديد من الثقافات الآسيوية، يأتي اسم العائلة قبل الاسم الأول.
• تخصيص التمثيل: تجاوز طريقة `to_representation()` في المُسلسل الخاص بك لتخصيص كيفية تمثيل البيانات المرتبطة.
• تحسين الأداء: للعلاقات المعقدة ومجموعات البيانات الكبيرة، استخدم تقنيات مثل `select_related` و `prefetch_related` لتحسين استعلامات قاعدة البيانات وتقليل عدد مرات الوصول إلى قاعدة البيانات. هذا مهم بشكل خاص لواجهات برمجة التطبيقات التي تخدم المستخدمين العالميين الذين قد يكون لديهم اتصالات أبطأ.
• التعامل مع القيم الفارغة (Null Values): كن على دراية بكيفية التعامل مع القيم الفارغة في المُسلسلات الخاصة بك، خاصة عند التعامل مع علاقات اختيارية. استخدم `allow_null=True` في حقول المُسلسل الخاصة بك إذا لزم الأمر.
• التحقق من الصحة: قم بتطبيق التحقق من صحة قوي لضمان سلامة البيانات، خاصة عند إنشاء أو تحديث الكائنات المرتبطة. ضع في اعتبارك استخدام مدققين مخصصين لفرض قواعد العمل. على سبيل المثال، لا ينبغي أن يكون تاريخ نشر الكتاب في المستقبل.
• التدويل والتوطين (i18n/l10n): ضع في اعتبارك كيف ستُعرض بياناتك بلغات ومناطق مختلفة. قم بتنسيق التواريخ والأرقام والعملات بشكل مناسب لمنطقة المستخدم. قم بتخزين السلاسل القابلة للتدويل في نماذجك ومُسلسلاتك.

أفضل الممارسات لعلاقات المُسلسل

• اجعل المُسلسلات مركزة: يجب أن يكون كل مُسلسل مسؤولاً عن تسلسل نموذج معين أو مجموعة قريبة من البيانات. تجنب إنشاء مُسلسلات معقدة للغاية.
• استخدم مُسلسلات صريحة: تجنب الاعتماد بشكل كبير على خيار `depth`. قم بتعريف مُسلسلات صريحة لكل نموذج مرتبط للحصول على مزيد من التحكم في عملية التسلسل.
• اختبر بشكل شامل: اكتب اختبارات وحدة للتحقق من أن المُسلسلات الخاصة بك تسلسل وتفك تسلسل البيانات بشكل صحيح، خاصة عند التعامل مع العلاقات المعقدة.
• وثق واجهة برمجة التطبيقات الخاصة بك: قم بتوثيق نقاط نهاية واجهة برمجة التطبيقات الخاصة بك بوضوح وتنسيقات البيانات التي تتوقعها وتعيدها. استخدم أدوات مثل Swagger أو OpenAPI لإنشاء وثائق API تفاعلية.
• ضع في اعتبارك إصدار API: مع تطور واجهة برمجة التطبيقات الخاصة بك، استخدم الإصدار للحفاظ على التوافق مع العملاء الحاليين. هذا يسمح لك بإدخال تغييرات كاسرة دون التأثير على التطبيقات القديمة.
• راقب الأداء: راقب أداء واجهة برمجة التطبيقات الخاصة بك وحدد أي اختناقات تتعلق بعلاقات المُسلسل. استخدم أدوات التنميط لتحسين استعلامات قاعدة البيانات ومنطق التسلسل.

الخاتمة

يعد إتقان علاقات المُسلسل في Django REST Framework أمرًا ضروريًا لبناء واجهات برمجة تطبيقات قوية وفعالة على الويب. من خلال فهم الأنواع المختلفة للعلاقات والخيارات المتنوعة المتاحة في مُسلسلات DRF، يمكنك تسلسل وفك تسلسل الكائنات المتداخلة بشكل فعال، والتعامل مع عمليات الكتابة، وتحسين واجهة برمجة التطبيقات الخاصة بك لتحقيق أقصى قدر من الأداء. تذكر أن تأخذ في الاعتبار التدويل والتوطين عند تصميم واجهة برمجة التطبيقات الخاصة بك لضمان سهولة الوصول إليها من قبل جمهور عالمي. يعد الاختبار الشامل والتوثيق الواضح مفتاحًا لضمان قابلية الصيانة والاستخدام على المدى الطويل لواجهة برمجة التطبيقات الخاصة بك.